Skip to main content

specialFolderPath

Type​

function

Summary​

Returns the names and locations of system-related folders.

Syntax​

the specialFolderPath of <folderIdentifier>
specialFolderPath(<folderIdentifier>)

Description​

Use the specialFolderPath function to place preferences in the Preferences folder, save files to the Documents folder, find out which files are installed in the System or Fonts folders, and so on.

If the folder is not found, the specialFolderPath function returns empty. If the folderIdentifier is either not supported on the current platform or doesn't exist on the current system, the result is set to "folder not found".

Some of the special folders you can specify with the specialFolderPath function need not have the standard names. (For example, the System Folder on Mac OS systems is not necessarily named "System Folder".) For this reason, the specialFolderPath function returns the full path to the folder, including the name of the folder.

On Windows systems, the folderIdentifier can alternatively be a Constant Special Item ID List (CSIDL) value that identifies a special folder. Note that not all CSIDL values work on all versions of Windows.

The following folderIdentifier values are supported:

  • Windows folder names:
    • "home": The current user's profile folder
    • "desktop": The current user's desktop folder
    • "documents": The current user's "My Documents" folder
    • "support": The current user's application-specific data ("AppData")
    folder 
  * \"system\": The Windows System folder
  * \"start\": The folder that contains Start Menu items
  * \"fonts\": The folder that contains fonts
  * \"temporary\": The folder where temporary files can be placed
  * \"engine\": The folder containing the LiveCode engine and the
    executable files copied in the standalone application
  * \"resources\": In development mode, the current stack\'s folder. In a
    standalone, the resources folder where files or folders specified
    in the Standalone Builder are located. Note: A valid resources path 
    is only returned after a stack has been saved.
  • Examples of common Windows CSIDL numbers:
    • 0x001a: Same as "support"
    • 0x0023: The application-specific data folder shared by all users
    • 0x000d: The current user's "My Music" folder
    • 0x000e: The current user's "My Videos" folder
    • 0x0027: The current user's "My Pictures" folder
    • 0x000a: The "Recycle Bin".

On Mac OS systems, the following folderIdentifier values are supported:

  • "home": The current user's home folder
  • "desktop": The current user's desktop folder
  • "preferences": The current user's preferences folder
  • "documents": The current user's documents folder
  • "support": The current user's application-specific data folder
  • "system": The System Folder (usually /System)
  • "fonts": The folder that contains fonts
  • "temporary": The folder where temporary files can be placed
  • "engine": The folder containing the LiveCode engine and the executable files copied in the < standalone application:::note[ "resources": In development mode, the current stack's folder. In a standalone, the resources folder where files or folders specified in the Standalone Builder are located. Note: a valid resources path is only returned after a stack has been saved.

]

On iOS systems*, only create files in the "documents", "cache" and "temporary" folders. Be careful not to change or add any files within the application bundle. The application bundle is digitally signed when it is built, and any changes after this point will invalidate the signature and prevent it from launching.

::: iOS imposes strict controls over what you can and cannot access. Each application in iOS is stored in its own "sandbox" folder (specialFolderPath(\"home\")). An application is free to read and write files anywhere beneath this folder, but it is not allowed to access anything outside of the "sandbox".

note

iOS devices have case-sensitive file systems, but the iOS simulator's file system has the same case-sensitivity as the host system (i.e. usually case-insensitive).

The following folderIdentifier values are supported:

  • "home": The (unique) folder containing the application bundle and its associated data and folders
  • "documents": The folder in which document data should be stored (backed up by iTunes on sync)
  • "library": The folder in which to store data of various types (backed up by iTunes on sync). In particular, data private to the application should be stored in a folder named with the app's bundle identifier inside the "library" folder
  • "cache": The folder where transient data that needs to be preserved between launches should be stored (not backed up by iTunes)
  • "temporary": The folder where temporary data that is not preserved between launches should be stored (not backed up by iTunes)
  • "engine": The folder containing the built standalone engine (i.e. the bundle). This is useful for constructing paths to resources that have been copied into the bundle at build time
  • "resources": Same as "engine".

On Android systems, note that the file system is case-sensitive.

An Android application is installed on the device as a ZIP package.
This means that any assets that are included are not available as separate files in the device's native file system. In order to manage this, LiveCode "virtualizes" the asset files you include, allowing read-only access with all the standard LiveCode file and folder handling commands and functions. To access the assets you have included with your application, use file names relative to specialFolderPath(\"engine\").

The following folderIdentifier values are supported:

  • "documents": The folder where application-specific data can be placed (typically valuable)
  • "cache": The folder where transient application-specific data can be placed (typically not valuable)
  • "temporary": Same as "cache"
  • "engine": The (virtual) folder containing the application's LiveCode engine and other resources that were copied into the application at build time
  • "resources": Same as "engine".
  • "external documents": The folder on the primary shared/external storage device where application-specific data can be placed
  • "external cache": The folder on the primary shared/external storage device where transient application-specific data can be placed
  • "external temporary": same as "external cache"
note

If using any external folderIdentifier values, ensure you have the 'Write External Storage' permission checked in the application standalone settings

On Linux systems, the following folderIdentifier values are supported:

  • "home": The current user's home folder
  • "desktop": The current user's desktop folder
  • "temporary": The folder where temporary files can be placed
  • "engine": The folder containing the LiveCode engine and the executable files copied in the < standalone application:::note[ "resources": In development mode, the current stack's folder. In a standalone, the resources folder where files or folders specified in the Standalone Builder are located. Note: A valid resources path is only returned after a stack has been saved.

]

In Web standalones*, you can read and write files from anywhere, since the whole file system is virtual and temporary. For compatibility purposes, the following folderIdentifier values are supported:

:::

  • "home": Always /livecode
  • "fonts": The folder that contains fonts
  • "temporary": A folder where temporary files can be placed
  • "engine": The folder where the standalone initial file system is extracted
  • "resources": The resources folder where files or folders specified in the Standalone Builder are located.

Parameters​

NameTypeDescription

folderIdentifier

enum

A string naming the special folder to locate (e.g. "home") or (on Windows only) a CSIDL value.

Examples​

local tPrefsFolder
put specialFolderPath("Preferences") into tPrefsFolder
set the defaultFolder to specialFolderPath("desktop")
local appSupportFolder
put specialFolderPath("asup") into appSupportFolder
local tFileContents
put url ("file:" \
      & specialFolderPath("engine") & slash & "foo.txt" ) into tFileContents
# get file listing of files in a given folder
on mouseUp
    local tMyImages
    put files(specialFolderPath("resources") & "/myimages") into tMyImages
end mouseUp

command: revSetDatabaseDriverPath

function: files, folders, tempName, result

glossary: application, application bundle, case-insensitive, case-sensitive, constant, engine, folder, platform, return, special folder, standalone application

property: defaultFolder

Compatibility and Support​

Introduced

LiveCode 1.1

OS

mac

windows

linux

ios

android

web

Platforms

desktop

server

mobile

Thank you for your feedback!

Was this page helpful?

Tags: